[% setvar title Organization and Rationalization of Perl State Variables %]
<div id="archive-notice">
    <h3>This file is part of the Perl 6 Archive</h3>
    <p>To see what is currently happening visit <a href="http://www.perl6.org/">http://www.perl6.org/</a></p>
</div>
<div class='pod'>
<a name='TITLE'></a><h1>TITLE</h1>
<p>Organization and Rationalization of Perl State Variables</p>
<a name='VERSION'></a><h1>VERSION</h1>
<pre>  Maintainer: Steve Simmons &lt;<a href='mailto:scs@ans.net'>scs@ans.net</a>&gt;
  Date: 3 Aug 2000
  Mailing List: <a href='mailto:perl6-language@perl.org'>perl6-language@perl.org</a>
  Number: 17
  Version: 2
  Status: Developing</pre>
<a name='ABSTRACT'></a><h1>ABSTRACT</h1>
<p>Perl currently contains a large number of state and status variables
with names that resemble line noise (henceforth called <code>$[linenoise]</code>
variables).
Some of these are (or should be) deprecated, and the naming methods for
the rest are obscure.  Since we are (potentially) adding, removing, and
changing the functionality of these variables with Perl6, we should seize the
opportunity to rationalize the names and organization of these variables
as well.  These variables need to be made available with mnemonic names,
categorized by module, be capable of introspective use, and proper
preparation made for deprecation and translation.</p>
<a name='DESCRIPTION'></a><h1>DESCRIPTION</h1>
<p><code>Perl</code> allows for the runtime examination and setting of a number of
variables.  These existing <code>$[linenoise]</code> variables are horrible names and
need cleanup, re-organization, and syntactic sugar.  Different variables
have different problems, usually one or more of the following:</p>
<ul>
<li><a name='unused (as far as we know)'></a>unused (as far as we know)</li>
<li><a name='useless, but still appear in older programs'></a>useless, but still appear in older programs</li>
<li><a name='duplicated by other features'></a>duplicated by other features</li>
<li><a name='standing in the way of advance because of backwards compatibility'></a>standing in the way of advance because of backwards compatibility</li>
</ul>
<p>In the pre-RFC discussion of this issue, it was also pointed out
that these variables are hard to deprecate without nagging the crap
out of users running the programs.  The proposed solution was
broadly applicable, and has been spun off into RFC 3.</p>
<p>The use of the <code>English</code> module is an attempt to solve the anti-mnemonic
features of these variables.  A better solution is to do it right in
the first place, with a number of attendant wins:</p>
<ul>
<li><a name='no need for Yet Another Module to be loaded'></a>no need for Yet Another Module to be loaded</li>
<li><a name='promotes code readability'></a>promotes code readability</li>
<li><a name='probably promotes core Perl maintainability'></a>probably promotes core Perl maintainability</li>
<li><a name='grouping sets of variables together by function gives the code writer strong hints as to variables that might affect each other'></a>grouping sets of variables together by function gives
the code writer strong hints as to variables that might
affect each other</li>
<li><a name='should we move formats (or any similar current core functionality) to a loadable module, this neatly encapsulates all the data with a single referenced name'></a>should we move formats (or any similar current core functionality)
to a loadable module, this neatly encapsulates all the data with
a single referenced name</li>
<li><a name='solves problems with $[linenoise] variable proliferation'></a>solves problems with <code>$[linenoise]</code> variable proliferation</li>
<li><a name='potentially promotes introspection - see below.'></a>potentially promotes introspection - see below.</li>
</ul>
<p>In addition, many features which are now (re)set by other calls should
set appropriate state variables as well.  Thus a <code>perl</code> script which
contains:</p>
<pre>    use strict foo;</pre>
<p>might set a var <code>$PERL_STRICT{foo}</code>, and so forth (this is probably
a poor example).</p>
<p>Credit where it is due: the idea of putting related values together into
an appropriately tagged hash is shamelessly ripped off from common <code>tcl</code> usage.</p>
<a name='Caveat - Global State Variables Are Dangerous'></a><h3>Caveat - Global State Variables Are Dangerous</h3>
<p>Having the setting of simple variables modify the function of a
broad set of things is an inherently dangerous and inelegant way of
doing things.  Mark-Jason Dominus &lt;<a href='mailto:mjd@plover.com'>mjd@plover.com</a>&gt; has proposed that
they simply be removed whenever possible.  I tend to agree with his
arguement, and join in urging that the problems he addresses in message
<code><a href='mailto:20000805171023.24408.qmail@plover.com'>20000805171023.24408.qmail@plover.com</a></code> be addressed by the core teams
working in the areas that use such variables.  The thread started my
Mark-Jason in <code>perl6-language</code> has a good discussion of the issues.</p>
<p>Notwithstanding, should the core team continue to allow global
variables for some purposes, the names and categorization should
be improved.</p>
<a name='Advantages and Non-Loses'></a><h2>Advantages and Non-Loses</h2>
<a name='Clean Backwards Compatibility'></a><h3>Clean Backwards Compatibility</h3>
<p>To promote backward compatibility, one could write a <code>use antiEnglish</code>
module which would alias the old names to the new ones.  That Would Be
Wrong, but someone will probably do it - so it may as well be us.
Obviously we cannot provide backwards compatibility for a variable
whose meaning has changed or which has vanished, but most of the
rest can be captured cleanly.</p>
<a name='Promoting Removable Core Modules'></a><h3>Promoting Removable Core Modules</h3>
<p>It has been strongly proposed that `core <code>perl</code>' be broken down internally
into a number of modules such that one could build smaller or larger
custom perls.  This feature would ease that work, and possibly set a
standard for how well-behaved non-core modules should implement such
things.</p>
<a name='Provide Possible Guidelines To Core-able Modules'></a><h3>Provide Possible Guidelines To Core-able Modules</h3>
<p>The discussion of removable core modules has strongly implied (sometimes
explicitly stated) that sites could take modules which are not currently
in the core and move them there.  Having a standard which those modules
could follow for variable setting and exposure would be a major win.</p>
<a name='Disadvantages'></a><h2>Disadvantages</h2>
<a name='Backwards Compatibility'></a><h3>Backwards Compatibility</h3>
<p>Existing <code>perl</code> code which makes use of <code>$[linenoise]</code> variables
which had not changed meaning in <code>perl6</code> will fail if (as proposed)
the variables are completely replaced by the names proposed here.
This is, at best, a minor objection because</p>
<a name='Increased Typing Considered Painful'></a><h3>Increased Typing Considered Painful</h3>
<p>A number of people have expressed great joy at the brevity of
the current names.</p>
<a name='Loss of Distinctiveness'></a><h3>Loss of Distinctiveness</h3>
<p>Currently when one sees a <code>$[linenoise]</code> variable,
they notice its specialness and have a visual clue to take care.
<code>$[linenoise]</code> stands out.
Since some of these variables have wide-reaching side-effects,
any solution should try to maintain that distinctiveness.</p>
<ul>
<li><a name='Few if any scripts match this description'></a>Few if any scripts match this description</li>
<li><a name='The proposed perl5 to perl6 translation tool should catch this and do the appropriate renaming.'></a>The proposed <code>perl5</code> to <code>perl6</code> translation tool should catch this
and do the appropriate renaming.</li>
</ul>
<a name='Other Possible Features'></a><h2>Other Possible Features</h2>
<p>It has been suggested by Alan Burlison &lt;<a href='mailto:Alan.Burlison@uk.sun.com'>Alan.Burlison@uk.sun.com</a>&gt;
that this allow for localizable settings.  Thus module A might
turns warnings off when its features are in use, while module
B is unaffected by the setting done by module A.  This is a change
in the functionality of such settings, and has the potential for
broadly changing what happens in <code>perl</code>.  I suggest that this
issue is actually independent of how the variables are named,
and should be taken to another RFC if anyone is interested.</p>
<a name='IMPLEMENTATION'></a><h1>IMPLEMENTATION</h1>
<a name='Internal Implementation'></a><h2>Internal Implementation</h2>
<p>The internal representation of these is largely irrelevant(!).
This RFC prescribes what the <i>external</i> interface looks like;
the implementation team should select whatever mechanism they
prefer for internal use.  It's probably a maintenance win if
the same is used, but the proposers don't intend to dictate
to the developers.</p>
<a name='External Implementation - Proposals'></a><h2>External Implementation - Proposals</h2>
<a name='Overall'></a><h3>Overall</h3>
<p>Variables should be sorted into functional areas which may or
may not have a one-to-one correspondence with internal (core)
There have been four suggestions for how the variables should
be named.</p>
<p>In the examples below, I have capitalized the higher-level
portions of the names.  This capitalization is not a requirement
of the RFC, and is done purely to make the new names stand out
in this document.</p>
<a name='Well-Named Global Hashes And Keys'></a><h3>Well-Named Global Hashes And Keys</h3>
<p>For each collection of variables, a well-named pseudo-hash with
well-named keys:</p>
<pre>  $PERL_CORE{warnings}          vs      $^W
  $PERL_CORE{version}           vs      $^V
  $PERL_FORMATS{name}           vs      $^
  $PERL_FORMATS{lines_left}     vs      $-
  $PSEUDO_HASHES{strict}        vs      (none)</pre>
<p>An additional variable should be provided,</p>
<pre>  $PERL_CORE{variables}</pre>
<p>which contains a list of all the settable hash names (eg,</p>
<pre>  $PERL_CORE{variables} = qw(PERL_CORE PERL_FORMATS PSEUDO_HASHES ...)</pre>
<p>Advantages: Only a single point in the namespace is used for each
variable.  The hashes can be handed around en masse efficiently
via references.  Pseudo-hash member access is efficient.
Names are free from module dependency.  Introspection with hashes
is more powerful (see below).</p>
<p>Disadvantages: Pseudo-hashes are new to most programmers.</p>
<a name='Well-Named Module Variable Sets'></a><h3>Well-Named Module Variable Sets</h3>
<p>This has an almost one-to-one naming match to the first suggestion,
but used module naming:</p>
<pre>  $PERL::CORE::Warnings         vs      $^W
  $PERL::CORE::Version          vs      $^V
  $PERL::FORMATS::Name          vs      $^
  $PERL::FORMATS::LinesLeft     vs      $-
  $PSEUDOHASH::CONTROL::Strict       vs      (none)</pre>
<p>Advantages: Looks like individual variables again.  Modules could
be moved (compiled) in and out of the perl core and, so long as
a script did the appropriate <code>use/require</code> statement, the script
would require no other changes.</p>
<p>Disadvantages: Locks variables into given modules.  The second-level
names may become difficult to do sensibly.</p>
<a name='Well-Named Per-Module Hashes And Keys'></a><h3>Well-Named Per-Module Hashes And Keys</h3>
<p>This is a hybrid of the first two:</p>
<pre>  $PERL::CORE{warnings}          vs      $^W
  $PERL::CORE{version}           vs      $^V
  $PERL::FORMATS{name}           vs      $^
  $PERL::FORMATS{lines_left}     vs      $-
  $PSEUDOHASH::CONTROL{Strict}   (none)</pre>
<p>Advantages: Looks like individual variables again.  Modules could
be moved (compiled) in and out of the perl core and, so long as
a script did the appropriate <code>use/require</code> statement, the script
would require no other changes.  Introspection and variable
discovery via <code>keys %PERL::CORE</code> is still a win.</p>
<p>Disadvantages: Locks variables into given modules.  The second-level
names may become difficult to do sensibly.  Introspection becomes
more difficult because one must find the second-level name(s) for
each class of item (eg, PERL::CORE and PERL::FORMATS).  Sometimes
there should not be More Than One Way To Do It - a single mechanism
makes it easier to notice, find, use, and understand such var.</p>
<a name='Introspection With Hashes'></a><h3>Introspection With Hashes</h3>
<p>The use of hashes and pseudo-hashes leads to a straightforward and
`natural' mechanism by which programmers can discover all the
relevant variables for a given item:</p>
<pre>   foreach my $key ( %PERL_CORE ) {
      print &quot;\%PERL_CORE{$key} is $PERL_CORE{$key}\n&quot;;
   }</pre>
<a name='Summary'></a><h3>Summary</h3>
<p>The RFC maintainer thinks the first suggestion, <i>Well-named Global
Hashes and Keys</i>, is the best choice.  While it has potential problems
for module removal should a hash be shared between several modules,
these are (IMHO) worth the flexibility of <i>not</i> locking a given hash to
a given module and providing a single, consistent mechanism programmers
would use to obtain value settings.</p>
<p>The community has not (as of version 1.1) expressed a strong preference
in either direction.</p>
<a name='Value Protection'></a><h2>Value Protection</h2>
<p>A value can be set and reset, but it's existence should be protected.
Thus one could set the variables, but not undefine or delete them.
If hashes are chosen, the user should not be allowed to add or
remove key/value pairs from the hash.</p>
<p>Further, values such as $<code>PERL_CORE{version}</code> should be read-only.</p>
<a name='Backwards Compatibility Issues and Suggestions'></a><h2>Backwards Compatibility Issues and Suggestions</h2>
<p>Backwards compatibility is an issue in two ways:</p>
<pre>=over4 </pre>
<li><a name='Moving old scripts to perl6'></a>Moving old scripts to <code>perl6</code></li>
<li><a name='Moving old coders to perl6'></a>Moving old coders to <code>perl6</code></li>
</ul>
<p>There are two solution sets for this, both of which should be implemented
as part of <code>perl6</code></p>
<a name='Variable Translation'></a><h3>Variable Translation</h3>
<p>The proposed script translator should catch all uses of pre-perl6
<code>$[linenoise]</code> variables and translate them to the new names according
to the guidelines below.</p>
<a name='Variable Remapping'></a><h3>Variable Remapping</h3>
<p>An <code>antiEnglish</code> module could be provided.
Like the current <code>English</code> module, this would attempt to map the new names
into the old <code>$[linenoise]</code> variables for those programmers absolutely
addicted to the old names.
It should handle the variables according to the guidelines below.</p>
<a name='Permanent Aliasing?'></a><h3>Permanent Aliasing?</h3>
<p>Several comments have been made (including one claimed to be second-hand
from Larry Wall) that they just don't like typing long variable names.
If this is a sufficently strong problem, the contributors to this RFC
would have no objection to having both variable namesets present
simultaneously.</p>
<p>This would have the advantage that the variables would still be
reorganized and grouped, and some additional introspection possible,
but the folks who are really married to the ultra-short names would
still have them available with no typing overhead.</p>
<a name='Guidelines for variable translation and remapping'></a><h3>Guidelines for variable translation and remapping</h3>
<p>The <code>perl6</code> conversion script should silently translate old
variable names to the new names when the meaning of the variable
is essentially unchanged.</p>
<p>The <code>antiEnglish</code> module should provide the old name as an
alias or map to the new name.</p>
<a name='Variables with changed meaning'></a><h4>Variables with changed meaning</h4>
<p>The <code>perl6</code> conversion script should translate old
variable names to the new names when there seems to be a reasonable
but not perfect mapping between the meanings of variables.
A one-time warning should be issued at compile time for each
use of such variables, similar to the manner in which the current
<code>perl -w</code> warns of first use of undeclared variables.
A comment should be inserted into the code above the use of the
variable saying something like:</p>
<pre>    # Comment inserted by PERL6_trans on &lt;date&gt;
    # Variable &lt;foo&gt; does not exist in perl6.  We have translated
    # it to &lt;bar&gt; below, but &lt;foo&gt; and &lt;bar&gt; are not completely
    # equivalent.  Please check your usage and make the appropriate
    # changes.</pre>
<p>In the best of all worlds, the comment might give hints as to
what to think about when changing that var.</p>
<p>The <code>antiEnglish</code> module should provide no mapping for these
variables.</p>
<a name='Variables which have been removed'></a><h4>Variables which have been removed</h4>
<p>The translator should leave removed variables which have been removed
in place, but a well-tagged <code>warn</code> statement should be placed above</p>
<p>The <code>antiEnglish</code> module should provide no mapping for these
variables.</p>
<a name='New variables'></a><h4>New variables</h4>
<p>Should the translator notice use of an existing variable with the
same name, it should ?print a warning and stop? ?print a warning and
go one? ?automaticly rename to prior var to l_?  TBD.</p>
<p>The <code>antiEnglish</code> module should provide no mapping for these
variables.</p>
<a name='Deprecation Warnings In Usage'></a><h2>Deprecation Warnings In Usage</h2>
<p>Programmers using hand-translated scripts or who attempt to run
untranslated scripts with <code>perl6</code> should get compile-time warnings
and errors, depending on severity of mis-use.</p>
<p>At a minimum, <code>use strict</code> and <code>perl -w</code> should warn of the
use of deprecated variable names.  That deprecation warning should
be <i>specific</i>, not simply <code>var <i>$foo</i> is deprecated</code>.  Messages
should identify the old var, new var, and at least imply an action.
Some possible samples include:</p>
<pre>  changing var $foo no longer has any effect, see &lt;doc module&gt;

  the value of var $bar no longer has any meaning, see &lt;doc module&gt;

  var $baz has been replaced by $FOO_BAR{baz}</pre>
<p>and so forth.</p>
<p>In addition, it should be possible to have the programmer detect
and control these messages on a case by case basis.  RFC 3 proposes
a mechanism by which programmers could take more direct control of
this; should that RFC be accepted then that mechanism should be used.
Should it fail, we will make a more specific recommendation here.</p>
<a name='CONTRIBUTIONS'></a><h1>CONTRIBUTIONS</h1>
<p>Contributions ranging from voluminous commentary to pretty
decent wisecracks have been received from:</p>
<pre>    Ted Ashton &lt;<a href='mailto:ashted@southern.edu'>ashted@southern.edu</a>&gt;
    &quot;J. David Blackstone&quot; &lt;<a href='mailto:jdavidb@dfw.net'>jdavidb@dfw.net</a>&gt;
    Corwin Brust &lt;<a href='mailto:cbrust@alldata.net'>cbrust@alldata.net</a>&gt;
    Alan Burlison &lt;<a href='mailto:Alan.Burlison@uk.sun.com'>Alan.Burlison@uk.sun.com</a>&gt;
    Piers Cawley &lt;<a href='mailto:pdcawley@bofh.org.uk'>pdcawley@bofh.org.uk</a>&gt;
    Tom Christiansen &lt;<a href='mailto:tchrist@chthon.perl.com'>tchrist@chthon.perl.com</a>&gt;
    Mark-Jason Dominus &lt;<a href='mailto:mjd@plover.com'>mjd@plover.com</a>&gt;
    Ken Fox &lt;<a href='mailto:kfox@vulpes.com'>kfox@vulpes.com</a>&gt;
    Chaim Frenkel &lt;<a href='mailto:chaimf@pobox.com'>chaimf@pobox.com</a>&gt;
    Jarkko Hietaniemi &lt;<a href='mailto:jhi@iki.fi'>jhi@iki.fi</a>&gt;
    Tim Jenness &lt;<a href='mailto:timj@jach.hawaii.edu'>timj@jach.hawaii.edu</a>&gt;
    Bart Lateur &lt;<a href='mailto:bart.lateur@skynet.be'>bart.lateur@skynet.be</a>&gt;
    Peter Scott &lt;<a href='mailto:Peter@PSDT.com'>Peter@PSDT.com</a>&gt;
    William Setzer &lt;<a href='mailto:William_Setzer@ncsu.edu'>William_Setzer@ncsu.edu</a>&gt;
    Dan Sugalski &lt;<a href='mailto:dan@sidhe.org'>dan@sidhe.org</a>&gt;
    &quot;Bryan C. Warnock&quot; &lt;<a href='mailto:bwarnock@gtemail.net'>bwarnock@gtemail.net</a>&gt;
    Nathan Wiger &lt;<a href='mailto:nate@wiger.org'>nate@wiger.org</a>&gt;</pre>
<p>and others who I probably missed.  In addition, it's been pointed
out that this suggestion was raised in the past; unfortunately the
fingerprints have long since worn away.</p>
<a name='REFERENCES'></a><h1>REFERENCES</h1>
<p>RFC 3 on Run-Time Error Message Control</p>
</div>
